How to manage Order Item Meta in WooCommerce

When viewing WooCommerce order items, you or your clients might want to have additional information on it. What if you have multiple shipping addresses and you want to see an address under each shipping rate? What if there some Fees on your orders which should have a detailed description? In this tutorial, we are going to see how to manage order item meta in WooCommerce.

Scenarios, where you’ll want to expand the order item meta data in WooCommerce, might not be so frequent, but after finishing this tutorial, you will probably have an idea where you could use this.

I came to this idea while working on a few projects with Grow Development and Shop Plugins. If you ever need to enhance your or a clients’ WooCommerce shop, be sure to check out their services and plugins.

At the end of the tutorial, you will see how we can add a shipping note under the shipping method for the delivery. This will let the delivery know when they can deliver the items.

Before we can go and add our own meta, we need to understand how the WooCommerce order item meta is stored and displayed.

Order Item Meta

Let’s learn where the item meta is stored first. WooCommerce stores the item data inside of two tables woocommerce_order_items and woocommerce_order_itemmeta. The latter one is the table that will hold the order item meta data. This table of the same structure as core WordPress meta tables such as postmeta. The only difference is that we don’t have a post_id column but a order_item_id which connects us with the item ID inside the table woocommerce_order_items.

The columns of the meta table are:

• meta_id – an ID that is autoincremented each time a new meta is added,
• order_item_id – the ID of the item in the order
• meta_key – the key used for storing the meta (and describing it)
• meta_value – the value of the stored meta

Displaying the meta

The order item meta in the order is always displayed using the same file woocommerce/includes/admin/meta-boxes/views/html-order-item-meta.php. Depending on the type of the item, it will be called in different files such as:

• Products (line items): woocommerce/includes/admin/meta-boxes/views/html-order-item.php,
• Shipping: woocommerce/includes/admin/meta-boxes/views/html-order-shipping.php,
• Fees: woocommerce/includes/admin/meta-boxes/views/html-order-fee.php

There are also other items and their meta such as coupons and taxes. But they won’t show the meta data.

The meta data is retrieved using the method get_formatted_meta_data. This method is defined within the class WC_Order_Item. Each meta is formatted into an array that contains:

• key – the value of the meta_key column,
• value – the value of the meta_value column,
• display_key – used for displaying the title of the meta. By default it is the same as key,
• display_value – used for displaying the value of the meta. By default it is the same as value.

We can filter the display_key and display_value with two filters.

Each meta array is then stored to an array with the key being the ID of the order meta data. The method get_formatted_meta_data then returns the array with all the meta data. We can also filter that array.

Hiding the Item Meta Data

If you’re storing item meta data for internal use only, you can hide them through the filter woocommerce_hidden_order_itemmeta. It is called in the file html-order-item-meta.php:

And here is how we can hide the meta data:

Order Item Meta Functions

There are several functions that allow us to add our own order item meta programmatically. All of the functions can be found inside of woocommerce/includes/wc-order-item-functions.php. You will also find functions to manage order items. But since this is a tutorial for order item meta data, we will only the item meta functions.

If you’ve ever worked with the core meta functions such as add_post_meta, you will find that these functions are the same.

Adding Order Item Meta

function wc_add_order_item_meta( $item_id, $meta_key, $meta_value, $unique = false )

The returned value is the ID of the order item meta or 0.

Deleting Order Item Meta

wc_delete_order_item_meta( $item_id, $meta_key, $meta_value = '', $delete_all = false )

This function will return true or false.

Updating Order Item Meta

wc_update_order_item_meta( $item_id, $meta_key, $meta_value, $prev_value = '' )

This function will also return true or false.

Getting Order Item Meta

wc_get_order_item_meta( $item_id, $key, $single = true )

This function will return the meta. The difference here is that you’ll get a single result by default. In core functions, you need to specify the $single as true if you want a single result.

Adding Order Item Meta on Checkout

If you’ve read everything up until now, congrats! You now have a basic knowledge on how you can manage order item meta in orders. Or at least, when the time comes, you’ll know there is a tutorial that can help you 😀

When you want to see how orders are created in WooCommerce, through checkout, you will have to look at their class WC_Checkout. This class is located at woocommerce/includes/class-wc-checkout.php.

So, when an order is being created, we can hook into various order items and add our own item meta. Methods that manage items and allow you to hook into each item are:

• create_order_line_items – for product items
• create_order_fee_lines – for fee items
• create_order_shipping_lines – for shipping items
• create_order_tax_lines – for tax items
• create_order_coupon_lines – for coupon items

Order Item Meta Filters

We need to understand filters inside each of those methods before you can use them to add your own custom order item meta data.

Product Items

The filter woocommerce_checkout_create_order_line_item accepts the item WC_Order_Item_Product, $cart_item_key which you can use for doing checks on the Cart, all the $values of that cart item and the $order itself.

Fee Items

In this method, the filter woocommerce_checkout_create_order_fee_item accepts the item WC_Order_Item_Fee, the fee key $fee_key, the whole $fee object and the $order.

Shipping Items

The filter woocommerce_checkout_create_order_shipping_item accepts the item WC_Order_Item_Shipping, the package key, the whole package and the order.

Do also check the other two methods mentioned above for their filters and what they pass on that you can use for other calculations 🙂

Adding a Shipping Item Meta data

We are now ready for an example. For this example, I will assume that we have a textarea field at the checkout for the shipping. It will be used as a shipping note for the delivery. You could use such field to tell the delivery that you are at home only from 12:00 to 19:00 so they don’t come too early or too late.

First, we will add the shipping item meta programmatically. We will use the filter woocommerce_checkout_create_order_shipping_item:

We are doing a basic check on the $_POST variable. If the note is set there and if there is any value, we will then add the meta with the method add_meta_data. If you also look closely, we are passing by reference the variable $item. This means that all the changes that we do inside the $item, will be there also outside of our hooked function.

The above image is now showing our meta where the title of that meta is the actual key. What if we want this key to look more as a title and not as a key used in the database? We will use the filter woocommerce_order_item_display_meta_key.

So, what are we doing here? We are checking for the key _note. If the current meta has that key, we will change that to Note. This way we can use the key _note elsewhere in the code and know that it will always be the same. But when we show the value of it, we will change the title so it looks more user friendly.

Conclusion

This was kind of a long tutorial but I hope you’ve learned something new. Most of what we have learned here can be also used for regular order items. You can search for the mentioned functions and methods and that can help you if you need to manage order items.

By managing and adding custom order item meta we can enhance even more the experience of the store owners but also of the store customers.

Have you ever had to do something with order items in WooCommerce? Let others now by sharing in the comments below.

 

Become a Sponsor